Developer CD Series 1997 October: Mac OS SDK/Dev.CD Oct 97 SDK1.toast/Development Kits (Disc 1)/AppleScript/Development Tools/Tools Goodies/AEGizmos 1.4.1/Documentation/AE Sub-descriptor Doc.dp

Common Ground | 1995-03-20 | 27.8 KB | 378 lines | [CGDC/CGVM]

TCGDC
Palatino
Apple Events
 Sub-Descriptors
AEGizmos Version 1.4
Jens Peter Alfke
20 March 1995
 Apple Computer, Inc. 1991
New York
Palatino
Apple Event Sub-Descriptors
3/20/95
Page
Introduction
OK, What Is It?
NThis library provides a high-efficiency way to examine and take apart (but not
!modify) Apple Event descriptors (
Courier
AEDesc
)$' structures). Almost everything is done
fOin place, without any copying of data, which avoids most of the overhead of the
KApple Event Manager. However, the API is very  similar to that of the Apple
8Event Manager, which makes it easy to convert your code.
K(Why are these functions read-only? Only one copy of the descriptor data is
Ostored, and descriptors within the main one are represented by offsets into the
Kdata. Changing one sub-descriptor would often involve inserting or deleting
Kdata, which would invalidate the offsets of all following sub-descriptors.)
s In It For Me?
>Speed, speed, speed
with very little of your code to modify.
NParsing complex nested Apple event descriptors (such as the object descriptors
Mused by the Apple Event Object Model) involves copying lots and lots of data.
"For instance, every time you call
AEGetNthDesc
)H% to get an element out of a list, all
fUthe data of that element (and of any descriptors nested within it, if it
s also an ar
f+ray or record) is copied into a new handle.
OThe functions in the
SubDescs library provide an interface that
s very similar
Kto a subset of that provided by the Apple Event Manager. (You should have a
Opretty easy job converting your code to use the library.) However, when you use
Wits routines to extract a nested descriptor, it doesn
t copy the data. Instead, it just
Qmakes a new descriptor that contains a (long integer) offset into the original de
fTscriptor
s data. The only time taken is that to find the location of the sub-descrip
tor in the data.
Palatino
The AppleEvent Stream Library
Page
3/20/95
s New?
In version 1.4:
Eyou can now create sub-descriptors on complete Apple events! An Apple
Fevent works like a record, where the items are the event
s parameters.
JAESubDescToDesc now properly copies the entire descriptor when the type is
DtypeWildCard and the sub-descriptor is the same as the whole AEDesc.
>Added AECopySubDescData at Dave Shaver's suggestion: it
s like
EAEGetSubDescData but copies the data rather than just pointing to it.
Palatino
The AppleEvent Stream Library
3/20/95
Page
!The Sub-Descriptor Data Structure
f1The new data structure involved is the AESubDesc:
Courier
typedef struct {
DescType
subDescType;
Handle
dataHandle;
offset;
} AESubDesc;
    AESubDesc
)6? represents an Apple Event descriptor nested within an existing
descriptor (
AEDesc
)$3). It contains a handle to some data
 which is the
.dataHandle
 of the existing
AEDesc
 as well as an offset into that descriptor's
fPdata. The offset points to the beginning of the nested sub-descriptor within the
    main one.
NThis way, when working with a lot of sub-descriptors of a main descriptor it's
8only offsets that are moved around, not the actual data.
Palatino
The AppleEvent Stream Library
Page
3/20/95
The Sub-Descriptor Functions
NITIALIZATION
AEDescToSubDesc
Courier
pascal OSErr
4AEDescToSubDesc( const AEDesc*, AESubDesc* result );
?This is how you begin. Given a regular Apple Event descriptor,
AEDescToSubDesc
NIsets up a sub-descriptor that starts out pointing to the main descriptor.
CCESSING
AEGetSubDescType
pascal DescType
%AEGetSubDescType( const AESubDesc* );
AEGetSubDescType
)`+ returns the type code of a sub-descriptor.
Zapf Dingbats
:If you want, you can also get this type directly from the
.subDescType
field of the sub-descrip
tor. Do
 modify this field!
Palatino
The AppleEvent Stream Library
3/20/95
Page
AEGetSubDescBasicType
Courier
pascal OSErr
?AEGetSubDescBasicType( const AESubDesc*, DescType *basicType );
AEGetSubDescBasicType
 is the same as
AEGetSubDescType
, with one exception: if
fIthe sub-descriptor is a coerced record, the type returned is typeAERecord
'reco'
AEGetSubDescIsListOrRecord
pascal Boolean
.AESubDescIsListOrRecord( const AESubDesc* sd )
AESubDescIsListOrRecord
6 returns true if the given sub-descriptor is a list, a
record,
or a coerced record
AEGetSubDescData
pascal void*
3AEGetSubDescData( const AESubDesc*, long *length );
AEGetSubDescData
)`@ returns a pointer to the data of a sub-descriptor, and sets the
length
)$6 parameter equal to the length of the data (in bytes.)
f#If the descriptor has no data (its
dataHandle
) then
 will be returned
and the
length
 parameter will be set to zero.
Zapf Dingbats
Warning
)D@Note that the pointer points within the descriptor's data handle
.dataHandle
)B2) and will become invalid if that handle is moved,
?purged or disposed as a result of a Memory Manager call. If you
want, you can lock the
dataHandle
)<" before this call, and restore its
Aprevious state later. Remember that all sub-descriptors retrieved
from a single
AEDesc
 share the same data handle!
Palatino
The AppleEvent Stream Library
Page
3/20/95
AECopySubDescData
Courier
pascal void
RAECopySubDescData( const AESubDesc*, long *length, const void *dst, long maxLen );
AEGetSubDescData
)`? copies the data of a sub-descriptor to the data buffer pointed
to by
, and sets the
length
)$6 parameter equal to the length of the data (in bytes.)
N$However, it will not copy more than
maxLen
)$( bytes to the buffer, even if the actual
length is greater.
#If the descriptor has no data (its
dataHandle
) then no data will be copied
and the
length
 parameter will be set to zero.
AESubDescToDesc
pascal OSErr
JAESubDescToDesc( const AESubDesc*, DescType desiredType, AEDesc* result );
AESubDescToDesc
)Z= copies a sub-descriptor into a brand new Apple event descrip
NJtor. (This calls the Memory  Manager and may move or purge memory blocks.)
OThe resulting descriptor will be coerced to the desired type; if you don't want
any coercion, use
typeWildCard
'****'
) as the desired type.
    CCESSING
RRAYS AND
ECORDS
NQThese calls are now safe: when passed descriptors that are not lists or (possibly
-coerced) records, they return the error code
errAEWrongDataType
 instead of
N    crashing.
RIn versions 1.3.5 and later, you can now use these calls on an entire Apple event.
NThe Apple event looks like a record whose items are the event
s parameters. As
>with any record, the order of the items is essentially random.
AECountSubDescItems
pascal long
(AECountSubDescItems( const AESubDesc* );
Palatino
The AppleEvent Stream Library
3/20/95
Page
Courier
AECountSubDescItems
)r0 counts the number of items in a sub-descriptor.
Zapf Dingbats
)&=If an error occurs, the result returned will be a (negative)
OSErr
 code
>instead of a (non-negative) length. You should check for this.
JCurrently the only way to get an error is to pass a descriptor that is not
.a list, record, or coerced record; you
ll get
errAEWrongDataType
 back.
AEGetNthSubDesc
#define
errAEListIsFactored
-1760
)6(// Can
t get items out of factored lists
pascal OSErr
JAEGetNthSubDesc( const AESubDesc* source, long index, AESubDesc* result );
AEGetNthSubDesc
)ZA gets an item out of an array or record or Apple event, given its
index. It sets up a new
)z    AESubDesc
)61 structure to point to the item; only a few bytes
of data are copied.
It's okay if
source
 and
result
)$2 point to the same sub-descriptor; it will be over
fOwritten with the new data. (This is not a memory leak since they share the same
dataHandle
VThis function will not work on factored lists; if the list is factored, the error code
errAEListIsFactored
)_( will be returned. (You could then call
AEGetSubDescData
 to copy the list
into a new
AEDesc
# and then retrieve its items using
AEGetNthPtr
AEGetNthDesc
AEGetKeySubDesc
pascal OSErr
IAEGetKeySubDesc( const AESubDesc* source, AEKeyword, AESubDesc* result );
AEGetKeySubDesc
)Z= gets an item out of a (possibly coerced) record, given a key
word. It sets up a new
)y    AESubDesc
)61 structure to point to the item; only a few bytes
of data are copied.
It's okay if
source
 and
result
)$2 point to the same sub-descriptor; it will be over
fOwritten with the new data. (This is not a memory leak since they share the same
dataHandle
Palatino
The AppleEvent Stream Library
Page
3/20/95
Zapf Dingbats
ZThis function will not work on factored records; if the record is factored, the error code
Courier
errAEListIsFactored
)_( will be returned. (You could then call
AEGetSubDescData
 to copy the list
into a new
AEDesc
# and then retrieve its items using
AEGetKeyPtr
AEGetKeyDesc
Palatino
The AppleEvent Stream Library
3/20/95
Page
The Header File
fKHere for your convenience is a printout of the .h file as of 17 March 1995.
Courier
// AESubDescs.h
U// A high-efficiency way to examine AEDescs. Everything is done in place, without any
Q// copying of data, which avoids most of the overhead of the Apple Event Manager.
I// By Jens Alfke; Copyright
1992-95 Apple Computer. All Rights Reserved.
#pragma once
#ifndef __AESUBDESCS__
#define __AESUBDESCS__
#ifndef __APPLEEVENTS__
#include <AppleEvents.h>
#endif
enum{
// Error code
errAEListIsFactored
= -1760
)Z(// I cannot get data from factored lists
struct AESubDesc {
DescType
subDescType;
)H1// Type of this subDesc. You may read this field.
Handle
dataHandle;
)H.// Handle to main (outer) descriptor. Private.
offset;
)H=// Offset into main descriptor where subDesc starts. Private.
#typedef struct AESubDesc AESubDesc;
#ifdef __cplusplus
extern "C" {
#endif
pascal void
-AEDescToSubDesc( const AEDesc*, AESubDesc* );
Palatino
The AppleEvent Stream Library
Page
3/20/95
Courier
pascal OSErr
?AESubDescToDesc( const AESubDesc*, long desiredType, AEDesc* );
pascal DescType
%AEGetSubDescType( const AESubDesc* );
pascal void*
CAEGetSubDescData( const AESubDesc*, long *length );dataHandle moves
pascal void
OAECopySubDescData( const AESubDesc *sd, long *length, void *dst, long maxLen );
pascal Boolean
/AESubDescIsListOrRecord( const AESubDesc* sd );
pascal DescType
*AEGetSubDescBasicType( const AESubDesc* );
pascal long
(AECountSubDescItems( const AESubDesc* );
pascal OSErr
1AEGetNthSubDesc( const AESubDesc* sd, long index,
) AEKeyword* keyIfAny, AESubDesc* newSD ),
r0AEGetKeySubDesc( const AESubDesc* sd, AEKeyword,
 AESubDesc* newSD );
#ifdef __cplusplus
#endif
#endif /*__AESUBDESCS__*/
6)3=*
p 0p`P
.!32/>
$:7%95
    temp.0001
Tme:_
Company:
Cancel
Jens Alfke
Apple Computer
Microsoft Word
New York
Zapf Dingbats
Palatino
Courier
bPREC
nPRVS
zCAPN